# spruce

**Table of Contents**

- [Intro](#intro)
    - [License](#license)
    - [Dependencies](#dependencies)
- [Learn](#learn)
    - [Structure](#structure)
    - [Units](#units)
- [Start](#start)
    - [Backup](#backup)
    - [Install](#install)
    - [Byte Compile](#byte-compile)
    - [Clean](#clean)
    - [Update](#update)
- [Customization](#customization)
    - [Temporary Cache](#temporary-cache)
- [Stop](#stop)
    - [Uninstall](#uninstall)
    - [Restore](#restore)

## Intro

[Spruce](https://notabug.org/_percival/spruce) is a set of Lisp scripts for setting up [GNU Emacs](https://gnu.org/software/emacs). The main goal of the project is high speed, extensibility, small size.

### License

[Spruce](https://notabug.org/_percival/spruce) is free software: you can redistribute it and/or modify it under the terms of the [GNU General Public License Version 3](https://gnu.org/licenses/gpl-3.0.html).

### Dependencies

For full operation, you need to install the dependencies:

- [git](https://git-scm.com) is software for tracking changes in any set of files.

For counsel and projectile:

- [ag](https://geoff.greer.fm/ag) is a text search tool.

For go-mode:

- [gopls](https://github.com/golang/tools/blob/master/gopls/README.md) is the language server for the go language.

For c-mode:

- [clangd](https://clangd.llvm.org) is the language server for the c language.

## Learn

### Structure

The project structure looks like this:

```
.emacs.d
  ┣━ .cache
  ┃    ┗━ tmp
  ┣━ .jit
  ┣━ .store
  ┣━ after-init
  ┣━ after-kill
  ┣━ after-use
  ┣━ before-use
  ┣━ local
  ┃   ┣━ after-init
  ┃   ┣━ after-kill
  ┃   ┣━ after-use
  ┃   ┣━ before-use
  ┃   ┣━ store
  ┃   ┣━ third
  ┃   ┣━ use
  ┃   ┗━ boot.el
  ┣━ store
  ┣━ third
  ┣━ use
  ┣━ init.el
  ┣━ LICENSE
  ┗━ README.md
```

To find out the actual paths for Lisp scripts and documentation, execute:

**C-h v**  `spruce--truedirectory` **TAB**

### Units

For ease of customization, an abstraction called units is used. This is a symbol and a list containing Lisp scripts and their directories.

To add new units execute the code:

```
(dolist (el (list :hello-world1 (list (concat spruce-local-before-truedirectory "hello-world1.el"))
                  :hello-world2 (list (concat spruce-local-before-truedirectory "hello-world2.el"))))
  (add-to-list 'spruce-units el t))
```

It is strongly recommended to place user settings in the file specified in the `spruce-boot-file` variable.

In order for the units to be executed at startup, you need to add them to the `spruce-load-units` list:

```
(dolist (el (list :hello-world1
                  :hello-world2))
  (add-to-list 'spruce-load-units el t))
```

There are `spruce-load-units-after-init` and `spruce-load-units-after-kill` units which are executed when `after-init-hook` and `kill-emacs-hook` are triggered.

If you want to [byte compile](#byte-compile) manually installed packages, you need to add the paths to them for the corresponding units:

```
(dolist (el (list :hello-world1 (list (concat spruce-local-store-truedirectory "hello-world1"))
                  :hello-world2 (list (concat spruce-local-store-truedirectory "hello-world2"))))
  (add-to-list 'spruce-user-packages el t))
```

The names of units must coincide and be enabled.

## Start

### Backup

To create a backup, execute the commands:

**~ $** `mv .emacs.d .emacs.d.bak`

**~ $** `mv .emacs .emacs.bak`

### Install

To install, execute the command:

**~ $** `git clone https://notabug.org/_percival/spruce ~/.emacs.d`

### Byte Compile

To byte compile all executable Lisp scripts from units, execute the command:

**M-x** `spruce-build`

### Clean

To remove all byte compiled Lisp scripts from units, execute the command:

**M-x** `spruce-clear`

### Update

To update Spruce from the git repository, execute the command:

**M-x** `spruce-update`

## Configuration

### Temporary Cache

If you need a temporary directory, use the directory specified in the value of the `spruce-cache-tmp-truedirectory` variable. But first you need to mount it to [TMPFS](https://kernel.org/doc/html/latest/filesystems/tmpfs.html).

To mount before the first shutdown of the system, execute the command:

**~ $** `mount -t tmpfs tmpfs PATH`

To mount each time the system starts, execute the command:

**~ $** `echo "tmpfs PATH tmpfs defaults 0 0" >> /etc/fstab`

## Stop

### Uninstall

To uninstall, execute the command:

**~ $** `yes | rm -r .emacs.d`

### Restore

To restore from backups, execute the commands:

**~ $** `mv .emacs.d.bak .emacs.d`

**~ $** `mv .emacs.bak .emacs`
